---
title: Initialize application manager
summary: Establishes the security principal on an AppManagerBase instance and delegates initialization and data-layer setup to the concrete subclass.
status: draft
owner: SAIF BOF documentation team
last_reviewed: 2026-08-21
library: SAIF.Application
reference_type: embedded
operation_id: OP-APP-001
trigger: Concrete subclass constructor/factory invokes the protected AppManagerBase constructor followed by Initialize()
---

# Initialize application manager

This operation describes the abstract initialization sequence every concrete `AppManagerBase` subclass follows: storing the security principal, then delegating initialization and data-layer setup to subclass-implemented hooks.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-APP-001 |
| **Trigger** | Caller (concrete subclass constructor/factory, outside this library) invokes the protected constructor, then calls `Initialize()` |
| **Inputs** | `clsSecurityPrincipal` |
| **Outputs** | Initialized instance with `SecurityPrincipal` set and `DataLayer` populated by the subclass |
| **Primary components** | `AppManagerBase.New`, `AppManagerBase.Initialize` |
| **Entry point** | `SAIF.Application\AppManagerBase.vb` |

## Steps

1. Caller invokes the protected constructor `New(inSecurityPrincipal As clsSecurityPrincipal)`, which stores the supplied principal in `SecurityPrincipal`. No business rule is enforced at this step and no SQL/table access occurs.
2. Caller invokes `Initialize()`, which calls `OnInitialize()` (abstract — implemented by the concrete subclass) followed by `OnCreateDataLayer()` (abstract — implemented by the concrete subclass). No business rule is enforced by `AppManagerBase` itself at this step ([BR-APP-004](../business-rules.md#br-app-004-retrieve-none-write-none-abstract-contract) requires every subclass to supply these implementations).
   - This step delegates to subclass-implemented hooks whose bodies are not present in this library — callee identity (library, class, operation) cannot be determined from this library's scope.**
3. `OnCreateDataLayer()` (subclass responsibility) is expected to populate `DataLayer` (an `ApplicationDataAccess` instance, lazily created on first access) with one or more named data portals via [Register a database connection portal](register-database-connection-portal.md), or via `AppManagerBase.InjectDPI(key, dpi)` to inject a pre-built `IDataPortalInfo` directly.
4. Every concrete subclass must also implement `OnContextChanged`, `OnCheckSecurity`, `OnTransactionStart`, `OnTransactionStop`, `OnRetrieve`, `OnWrite`, `OnValidContext`, `Retrieve`, and `Write` ([BR-APP-004](../business-rules.md#br-app-004-retrieve-none-write-none-abstract-contract)); the VB.NET compiler prevents instantiation of any subclass that omits one of these members.
   - Inherited edit-session and rule-evaluation machinery from `clsBusinessBase` (`BeginEdit`/`ApplyEdit`, rule evaluation, save dispatch) is available on the instance but no direct evidence in `AppManagerBase.vb` shows it being invoked by this library's own code.*

   > **Origin**: The inherited edit-session/rule-evaluation/save machinery referenced above is implemented in `clsBusinessBase` (`SAIF.Framework.Core`) and made available to every `AppManagerBase` instance through inheritance; no local operation document exists for it because it originates from a dependency framework library, not an in-repo project reference.

## Process flow

The following diagram visualizes this operation's control flow.

```mermaid
flowchart TD
	Start([Concrete subclass constructor]) --> S1[Store SecurityPrincipal]
	S1 --> S2[Call Initialize]
	S2 --> S3[OnInitialize - subclass hook]
	S3 --> S4[OnCreateDataLayer - subclass hook]
	S4 --> D{Portal registration needed?}
	D -->|Yes| S5[Register data connection portal]
	D -->|No / InjectDPI used| EndOk([Instance ready])
	S5 --> EndOk
```

## Failure and edge-case behavior
- If a concrete subclass omits any `MustOverride` member, the VB.NET compiler prevents instantiation entirely — this is a compile-time, not runtime, failure mode.

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)
- [API reference](../api/index.md)

> **Note:** Statements marked with `*` were inferred from code structure, naming
> conventions, or contextual evidence where direct confirmation was not available
> in source artifacts. Statements marked with `**` could not be confirmed; treat
> as unknown until verified.

## Sources
- `SAIF.Application\AppManagerBase.vb`